home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
MacWorld: Complete Mac Interactive
/
Macworld Complete Mac Interactive CD)(1994).iso
/
The Best of BMUG
/
Utilities
/
Text and Speech
/
Alpha.5.76
/
Help
/
Alpha Commands
next >
Wrap
Text File
|
1994-03-08
|
28KB
|
561 lines
==============================================================================
= Alpha Commands
==============================================================================
In this list of routines, text between '<' and '>' is a placeholder for a
required parameter, text between '[' and ']' is a placeholder for an
optional parameter, and the '|' signifies a choice of two or more
alternatives. A '+' signifies that the previous symbol can be present one
or more times, while a '*" means zero or more times. Some commands have no
parameters, and are only expected to be called interactively.
The following are Alpha-specific tcl routines:
• abortEm - aborts whatever is currently happening
• addMenuItem [-m] [-l <meta-characters>] <menu name> <item name> - Convert
item to menu form and add to specified menu. If '-m' specified, menu
form conversion not done. The '-l' option allows you to use menu meta
characters as text of menu items. If the '-l' option is used, the
<meta-characters> string is interpreted for menu item attributes, and
meta-characters in <item name> are included in the menu item text
literally. For example:
addMenuItem -m -l "/B" "Hello/C"
would appear as the text "Hello/C" in the menu, and have "B" as its
command equivalent.
• AEBuild <app name> <aesuite> <action> <build spec> - Build and send an
apple-event. 'AEBuild' is apple's code of the same name. The syntax of
this command will change. However, feel free to play with it as is.
• alertnote message_string
This command will display message_string in a standard Macintosh alert box.
• alphaHelp - display Alpha help.
• ascii (see bindings).
• askyesno prompt
This command will display a Macintosh alert box with 'prompt' displayed
with the push buttons Yes and No. The command will return the
string "yes" or "no".
• backColor - set background color
• backwardCharSelect - extends selection one char back
• backwardChar - moves insertion one char back
• backwardDeleteWord - deletes previous word
• backwardWord - moves insertion one char back
• balance - selects smallest set of parens, braces, or
brackets that encloses the current selection
• beep
• beginningBufferSelect - extend selection to the
beginning of the buffer
• beginningLineSelect - extend selection to the
beginning of the line
• beginningOfBuffer - move insertion to the beginning
of the buffer
• beginningOfLine - move insertion to the beginning of
the line
• bind (see bindings)
• blink <pos> - blink cursor at 'pos'
• breakIntoLines <string> - return 'string' with
carriage returns and spaces inserted to satisfy
'leftFillColumn' and 'fillColumn' variables.
• bringToFront <winName> - Bring named window to front.
• capitalizeRegion - capitalize all words in selected
region
• capitalizeWord - capitalize word
• cd [directory]
This command will set the current working directory to "directory". The directory
argument may or may not end with a colon. The working directory is the directory
in which file names that contain no colons (folders) will be located with file related
commands. No argument means Alpha's home directory.
• centerRedraw - redraw window with current line in
the middle.
• clear - clear selected text
• closeAll - close all windows
• colorize <fromPos> <toPos> <black blue cyan green green magenta red white yellow> -
Change the color of the specified region.
• colors <fore red> <fore green> <fore blue> <back red> <back green> <back blue>
• copy - copy region
• cp <fromName>+ <toName>
This command will copy the file fromName and name the new file toName,
overwriting any existing file. This command copies both data forks, and
the Finder information.
• createTagFile - searches all files in current file set
and saves the locations of any function declarations
in a file called 'cTAGS'.
• createTMark <name> <pos> - create a temporary 'mark'
at location 'pos'.
• currentPosition - displays current and total bytes.
• cut - deletes and saves region
• deleteChar - delete char AFTER cursor
• deleteMenuItem [-m] <menu name> <item name> - Convert item to menu form
and delete from specified menu. If '-m' specified, menu form conversion
not done.
• deleteSelection - delete current position, don't save
• deleteWord - delete word after cursor
• describeBinding - display the binding of the next typed key sequence.
• deleteText <pos1> <pos2> - remove text between 'pos1'
and 'pos2'
• displayMode <mode> - Up to four characters of the 'mode' string are
displayed in the status line at the bottom of a window.
• dosc [<-c 'sign' | -n appName>] [-k 'clas'] [-e 'evnt'] <-s string | -f fileName> [<-t timeout|-r>]
Send an AppleEvent, by default class 'misc', event 'dosc'.
-c 'sign'
"sign" is a four-letter creator signature of a running application.
-n appName
"appName" is the name of a running application.
-k 'clas'
"clas" is a four-letter event class.
-e 'evnt'
"evnt" is a four-letter event class.
-s string
"string" is the text of a script to send to the other app.
-f fileName
"fileName" is the complete or relative pathname of a file the other
application should execute.
-t timeout
"timeout" is the number of ticks Alpha should wait for a response. A
timeout of "0" means wait forever.
-r
Do not wait for reply.
If neither of the '-c' and '-n' options is chosen, the PPC Browser is
used. Either '-s' or '-f' must be chosen. Thus, you can have "Alpha
5.02" and "Alpha 5.02 Copy" sending Apple events to each other, or they
can send events to a remote server such as Apple's ToolServer.
"$HOME:Tcl:UserCode:createStuffitArchive.tcl" contains examples of
controlling Stuffit Deluxe via this command.
• downcaseRegion - changes all uppercase letters to
lowercase in current region
• downcaseWord - changes all uppercase letters to
lowercase in current word
• dumpColors - dump current foreground and background
colors into the current buffer in Alpha-readable
format.
• dumpMacro - prompts for a name and then dumps a tcl proc representation
of the current keyboard macro into the current window.
• echo <string>* - echo the strings (used
in shells).
• edit <name> [-r] [-m] - Open a file in a new window. '-r' means open
the file read-only. '-m' means omit the function titlebar menu and
present only the marks titlebar menu, which is labeled with the
contents of 'markLabel'.
• endBufferSelect - extend selection to the end of the
buffer
• endKeyboardMacro - stop recording keyboard macro
• endLineSelect - extend selection to the end of line
• endOfBuffer - move insertion to the end of the buffer
• endOfLine - move insertion to the end of the line
• exchangePointAndmark - exchange the current 'mark'
w/ the current insertion point
• execute - prompt user for a function or macro. The
tab key acts as a "completion" command.
• executeKeyboardMacro - execute the current keyboard
macro
• fileInfo - prompts for a file, and displays type,
creator, sizes of both data and resource forks, last
modification time, and creation time
• fileRemove - prompts for a file, and removes it
• findTag - prompt user for a function name and attempt
to use the file 'cTAGS' to locate the function's
definition
• find - bring up the find dialog
• findFile - open a file in a new window
• foreColor - set foreground (text) color
• forwardCharSelect - extend selection one character
forward
• forwardChar - move insertion one character forward
• forwardWord - move insertion one word forward
• freeMem - give a rough approximation of the current
memory reserves of ALPHA
• get_directory
This command will display a standard Macintosh file dialog and request the user
select a folder. The command will return the selected folder's full path name, or an
empty string if the Cancel button was selected.
• getAscii - displays the ASCII code for character at
current insertion point
• getfile <prompt>
This command will display an SFGetFile() and return the full path name of the
selected file, or an empty string if CANCEL button was selected.
• getfinfo <fileName>
This command will display the standard Macintosh file information in the form:
"'aeQL' 'QUIL' lvbsIdm 02/17/92 23:57:12 02/19/92 22:43:36 0,156 219 0".
The fields are the fdCreator, fdType, fdFlags, flCreationDate, flCreationtime,
flModDate, flModTime, fdLocation.H,V, dataForlLength, rsrcForkLength,
respectively. The fdFlags field uses characters to represent bits:
l/L not locked/Locked
v/V visible/notVisible
b/B not bundled/Bundled
s/S not system/System
i/I not initialized/Initialized
d/D not desktop/Desktop
m/M not sharable/sharable
• getGeometry - return a TCL list containing the left
edge of the current window, the top, the width, and
height.
• getline <prompt> <default>
This command will display a Macintosh alert box with prompt displayed, a
text edit field with default initially in the field, and with the push
buttons OK, Cancel.. The command will return the text entered into the
text edit field by the user, or an empty string if the user selected the
Cancel button.
• getMainDevice - return a list containing the left, top, right, and
bottom of the rectangle defining the main device.
• getMark - return the current mark.
• getPathName - prompt the user with an SFGetFile dialog and return
complete pathname.
• getPos - return the current insertion point
• getScrap - returns system TEXT scrap.
• getSelect - return the currently selected text, if
any.
• getTMarks - Return a list of temporary marks. Each item of the returned
list is a sublist containing the mark name, the complete pathname of the
mark, and the start and finish of the selection named by the mark. The
following is an example of the result:
{{temp1 External:file.c 1312 1315} {temp2 Internal:it.h 111 111}}
• getText <pos1> <pos2> - return the text between 'pos1'
and 'pos2'.
• glob [-i] [-t <TYPE>] [-c <CRTR>]
The original glob provided by the UNIX version of tcl was not quite
adequate for the more complex Macintosh file system. Issues such as
invisible file handling, Finder type and creator filtering, and space
handling in file names. Release 6 of tcl has dealt with the original
problem with spaces in filenames, but the following options are provided
to deal with additional Macintosh issues.
Anyway, the new glob now takes several options. They are:
-i This option causes glob to list invisible files also.
-t TYPE This option causes glob to only list file with the
indicated Finder file typeTYPE. This option may be
used with the -c option.
-c CRTR This option causes glob to only list file with the
indicated Finder file creatorCRTR. This option may
be used with the -t option.
Also note that the original glob would skip dot files
(i.e., file names the begin with a period)
in the listing, unless the pattern began with a period.
Tickle extends this concept one step further on the
Macintosh, and skips spot files (i.e., file names that
begin with '•'), unless the pattern starts with a spot.
• goto <pos> - goto the position 'pos'.
• gotoLine - go to a line number
• gotoMark - goto named mark, use 'mark' in macros.
• gotoTMark <name> - goto the temporary mark 'name'.
• enableMenuItem <menuName> <item text> <on|off> - Either enable or
disable the menu item of user menu 'menuName' that has text '<item
text>'. Note that unless the menu is not only created, but also already
inserted, this command has no effect.
• icon [-f <winName>] [-c|-o|-t|-q] [-g <h> <v>] - Having to do w/
iconifying windows. '-c' means close (iconify) window, '-o' open, '-t'
toggle open/close, '-q' returns either a '1' for an iconified window or a
'0' for an uniconified window, and '-g' moves the icon to horizontal
position <h> and vertical position 'v'. Options are executed as they
are parsed, so the '-f' option, if present, should always be first.
• includeFile - expand the current selection to include
the suffix and use the var 'includePath' to try to
find the include file.
• indentLine - semi-intelligent indent. If cursor is
before first non-white space of line, the line is
indented and the selection is placed at the start
of the non-white space text
• insertAscii - prompts for an ASCII code and inserts
into text.
• insertFile - prompts for a file name and inserts the
corresponding file into the current window. Not
undoable.
• insertMenu <name> - insert the previously created user menu 'name' into
the menuBar.
• insertPathName - present the user w/ a SFGetFIle dialog
and paste the complete path-name of the chosen file
into the current window
• insertText [-w <win name>] <text>* - Insert 'text' at the current
insertion point.
• insertToTop - make the line that the insertion point
is on the first line shown, and display the current
line number along w/ the total number of lines in file
• isearch - incremental search: searches w/o a dialog,
searches as you type the search pattern. Does not do
regular expression searches. 'matchWords'
automatically set to false.
• iterationCount - allows actions to be repeated many times. "option-u 44
=" inserts 44 '='s into current window. Also can be used to execute any
function or macro (including the keyboard macro) many times. Defaults to
4.
• keyAscii - insert ascii representation (in decimal)
of the keydown event, plus a modifier string, if
necessary.
• keyCode - insert the key code along w/ a string
representing and modifiers into the current window.
Can be used to create bindings in 'Alphabits'.
• killLine - kill text from insertion point to the end
of the line. If the line has no text, delete the line
and move succeeding lines up one.
• killWindow - kill current window
• launch -f <name> - launch the named app into the background. Note that
for some yet unexplained reason, some applications (MicroSoft Word)
won't launch completely in the background. 'launch'ing such
applications won't insert the application into any system menu that
specifies running applications (although "About the Finder..." will
list it. The only way to get to such an app is through Alpha's
'switchTo', after which the application will finish launching. The '-f'
option gets around this by launching the application in the foreground
instead.
• lineStart <pos> - return the position of the start of
the line 'pos' is on.
• listBindings - list all current bindings.
• listpick [-p <prompt>] <list>
This command will display a dialog with the list displayed in a List Manager list. If
the user presses the Cancel button, an empty string is returned. If the user selects
the Open button, or double clicks an item in the list, that item will be returned.
• load - loads hilited text, or entire window if
nothing is hilited. 'load'ing means that whatever
bindings or macro definitions are present in the
loaded text take effect
• lookAt [-w <name>] <pos> - return the 'pos'th character of the
current file, or the file named by <name> if the '-w' option is specified.
• makeMenuPermanent <name> - The named menu is no longer deleted from the
menubar in response to subsequent 'removeMenu' calls.
• markHilite - This is the 'Hilite' from the 'Edit'
menu. If there is a currently hilited selection, the
selection is unhilited, leaving the mark and the
insertion point around the old selection. If there
is not a selection, the region between the insertion
point and the mark is selected.
• markMenuItem [-m] <menuName> <item text> <on|off> [<mark char>] - Either mark or unmark
the menu item of user menu 'menuName' that has text '<item text>'.
Note that unless the menu is not only created, but also already
inserted, this command has no effect.
• matchBrace - moves the insertion point to the
character that matches the character after the current
insertion point
• matchIt <brace char> <pos> - Return pos of matching brace. Recognizes
parenthesis, square brackets, and curly braces.
• maxPos - returns the number of characters in the front
window.
• menu [-n <name>] [-i <num] [-m] [-p <procname>] <list of menu items> - Defines a
new menu named 'name' (if provided w/ '-n' option). The menu is not yet
inserted into the menubar. The menu commands may be nested for
heirarchical menus, see 'AlphaBits.tcl' for examples. Alpha massages the
function names to make them look better in the menus.
'-n <num>' Resource id of icon suite to use for menu title. 'ics#'
is the only resource that is really necessary.
'-n <name>' Name the menu. Not necessary for submenus.
'-m' No menu form. If not supplied, each menu item is split into
words at each capitalized letter.
'-p <name>' The tcl proc named by 'name' is called w/ the menu item's
contents as it's single argument when the item is chosen. If the
proc returns "normal" as its result, the menu item is executed as
if no proc had been specified.
• message <string> - prints 'string' on the status line.
• mkdir <name> - creates a directory (folder) named
'name' in the current directory.
• mousePos - Returns list <row,col> of mouse position, if the mouse is
currently over the active window. Otherwise, return error (catch w/
'catch').
• moveInsertionHere - move the insertion point to the
first line displayed
• moveWin [win name] <left> <top> - moves current or specified window.
• mtime <time> [long|short|abbrev]
Returns a date and time string using the Macintosh International Utilities. The
long/short/abbrev specification corresponds to the date. These are the following
formats:
short 3/16/92 9:20:46 PM
abbrev Mon, Mar 16, 1992 9:20:49 PM
long Monday, March 16, 1992 9:20:43 PM
The returned value actually is in the form of a list. To get text as
above, run the result through 'join', as in "join [mtime [now] short]".
• moveFile <fromName> <toName>
This command will move the file fromName to toName, overwriting any
existing file. The move can not be made across volume (disk drives)
boundaries.
• new - opens an untitled window
• nextLine - move insertion point to next line
• nextLineSelect - extend selection to the next line
• nextLineStart <pos> - return the position of the start
of the next line after position 'pos'.
• nextSentence - go to next sentence ("fill.tcl").
• nextWindow - select next window
• now
Returns the current time as Macintosh seconds. This is the number of seconds that
have elapsed since Midnight Jan 1, 1904.
• oneSpace - converts whitespace surrounding insertion
into a single space.
• openLine - insert a new line following the current
one and move the insertion point to it
• pageBack - display prev screenful, move the
insertion point if 'moveInsertion' enabled
• pageForward - display next screenful, move the
insertion point if 'moveInsertion' enabled
• pageSetup - display the printing PageSetup dialog.
• paste - insert the last chunk of text created by 'cut'
or 'copy'
• posToRowCol <pos> - converts from absolute position to row, col.
• prefixChar - used to further modify the next keystroke
combination, in the same manner as using the shift key
in the next keystroke
• prevLineSelect - extend selection to the previous line
• prevSentence - go to previous sentence ("fill.tcl").
• prevWindow - select previous window
• previousLine - move insertion point to the previous
line
• print - print front window
• processes - returns info of active processes. A list of lists, each
sublist contain a file-name, an application signature, the application
memory size, and the number of ticks the application has been active.
• prompt <prompt> <default> [<name> <menu item>*] - prompt dialog to
the user with a prompt string and a default value. The prompt dialog can
optionally include a popup menu specified by 'name' and the succeeding
strings. Selection of the popup menu items inserts the item text into the
editable dialog item. 'Prompt' returns the value of the editable item.
If the 'Cancel' button is selected, the tcl returns an error and your
script will be stopped unless you execute the command from 'catch'.
• putfile <prompt> <original>
This command will display an SFPutFile() and return the full path name of the
selected file, or an empty string if CANCEL button was selected. Original is the
default name displayed for the user.
• putScrap [<string>]+ - Concatenate strings together into the system
scrap. The scrap can be appended to through calls of the form 'putScrap
[getScrap] " another word"'.
• pwd
This command will return the current working directory.
• quit - quits ALPHA
• rectMarkHilite - creates a rectangular selection
between the mark and the insertion point.
• redo - redo the next action that has been undone but
not redone
• removeMark - allows marks to be removed.
• removeMenu <name> - remove menu 'name' from menubar, except those
specified by previous 'makeMenuPermanent' calls.
• removeTMark <name> - remove temporary mark.
• repeatSearchBackward - repeat search backward
• repeatSearchForward - repeat search forward
• replaceText <pos1> <pos2> [text]+ - replaces the text
between 'pos1' and 'pos2' with 'text', where 'text' can be any number
of arguments. Leaves insertion at end, mark at beginning of inserted
text.
• removeColors [-f <win name>] - remove all colors from window.
• removeFile <fileName>
This command will delete the file or folder 'fileName'.
• restoreVars - restore variables to saved state,
see 'saveVars'
• revert - revert the file to it's last saved version
• rowColToPos <row> <col> - converts to abosolute position.
• rsearch - reverse incremental search, see 'isearch'.
• save - save current window
• saveAs - save current window with new name
• saveVars - save variable state, see 'restoreVars'
• scrollDownLine - same action as that which occurs when
the down arrow in the vertical scrollbar is selected
• scrollLeftCol - same action as that which occurs when
the left arrow in the horizontal scrollbar is selected
• scrollRightCol - same action as that which occurs when
the right arrow in the horizontal scrollbar is
selected
• scrollUpLine - same action as that which occurs when
the up arrow in the vertical scrollbar is selected
• search [-f <num>] [-r <num] [-i <num>] [-m <num] [-n] [-l <limit>] [--] <pattern> <pos> -
Searches for 'pattern' from position 'pos'. The '-f', '-r', '-i', and
'-m' options allow the 'forward', 'regExpr', 'ignoreCase', and
'matchWord' internal variables to be set. The '-l' option allows a
search limit to be set. The search fails if the a match is not found
totally contained between 'pos' and 'limit'. A '--' option specifies
that the flags are finished and that the next arg is the pattern. The
'-n' option specifies that a failed search still returns TCL_OK.
However, the result of the call is then just an empty string. If the
search succeeds, a list of two positions will be returned. The first is
the starting position of the match, the second is one past the last
character.
• enterSelection - use current selection for future searches.
• findInNextFile - search next file.
• replaceAll - replace all further occurrences in the current file.
• replace - replace the current selection
• replace&FindAgain - replace the current selection and find next
occurrence.
• select <pos1> <pos2> - selects the text between 'pos1'
and 'pos2'.
• selEnd - returns the end of the hilited selection, or
the current insertion point if no text is selected.
• sendOpenEvent <-n app name> <file name> - Send an open doc event to
another currently running application.
• sendToBack <winName> - Sent named window to back.
• setfinfo <fileName> [-a flags] [-c fdCreator] [-t fdTypes]
This command will set the standard Macintosh file information. The flags setting
must be of the same format as displayed by the getfinfo flag.
• setMark - set the current mark to the insertion point
• setFontsTabs - bring up font and tab dialog
• setNamedMark [name disp pos end] - set named mark. If optional arguments are
present, the mark is created with prompting user. 'disp' is the
character position of the start of the first line to be displayed,
while 'pos' and 'end' bracket the text to be selected.
the first char
• shadowVar <name> - Associates a Tcl variable with an Alpha variable of
the same name. Writes to the Tcl variable automatically are copied to
the Alpha variable.
• shell - open the Tcl shell.
• shiftLeftRegion - shifts the current region left a tab
• shiftRightRegion - shift the current region right a
tab
• sizeWin [win name] <width> <height> - sets size of current or specified window.
• sortMarks - sorts all marks of open windows, w/o
setting the dirty flag. If the files are saved, the
marks will be saved in alphabetical order.
• spacesToTabs - convert spaces in selection to tabs
• startEscape - used to further modify the next
keystroke combination, in the same manner as using the
shift key in the next keystroke
• startKeyboardMacro - start recording keyboard macro
• substituteVars <string> - Takes a single string and
substitutes for all variables inside it, regardless of
depth. Unfortunately, you currently need to make 'global var'
declarations in the proc you call this for each 'var' that might need
to be substituted in the string (see proc.tcl for examples).
• switchTo <appName> - Switches to application 'appName'.
• tab - insert a tab
• tabsToSpaces - convert tabs in selection to spaces.
• tclFileCompletion - completes the previous word as a
file is in a shell window
• tclResult - displays a dialog showing the result of
the last TCL evaluation.
• thinkReference <-t|-l> <think reference page> - Interact with Think
Reference 2.0. '-t' retrieves a template without leaving Alpha, '-l'
switches to Think Reference and goes to the specified page.
• ticks
Returns the current TickCount. Ticks are 60ths of a seconds. TickCount is the
number of ticks since the Macintosh was started. The command:
puts stdout [expr "[ticks] / 60"]
will print the number of seconds since the Macintosh was booted.
• toggleScrollbar - toggles horizontal scrollbar on frontmost window.
Will not succeed if scrollbar scrolled.
• traceFunc on <funcName> <winName> Trace 'funcName', send output to
'winName'.
traceFunc off Turn function tracing off.
traceFunc status Display current tracing status.
• undo - undo the last action that has not been undone
• upcaseRegion - convert all lowercase letters to
uppercase in the current region
• upcaseWord - convert all lowercase letters to
uppercase in the current word
• version - Return string of the form "Alpha Version 5.31, Feb. 15, 1993".
• watchCursor - turns the cursor into a a watch cursor.
• wc <file>... - counts chars, words, lines of input files.
• winFuncTitle <winName> <title> - Sets the title of the leftmost
titlebar menu. See the section on "TitleBar Menus" in "General Help".
• winNames [-f] - return a TCL list of all open windows. If '-f' option
specified, complete pathnames are returned.
• wrap - see the section on "Fill" routines.
• wrapText
• xtclcmd [-f filename] <cmdname> [argument_list]*
This command will load the external command cmdname and pass it the argument
list [ cmdname argument_list... ]. External command are code resources of type
XTCL. They may be located in the resource fork of the tickle application, or they
may be located in a file named XTCL File in the same directory as the tickle
application. If the optional -f filename is included, the external command will first
be loaded from filename before the other two files.
See the appendix for a detailed description of the external tcl command interface.
See the accompanying sources for an example of writing an XTCL.
• yank - insert the last piece of deleted text of less
than 1k. Consecutive deletes are concatenated.
together.
• zapInvisibles - removes chars < ascii 32, except for
LF's and CR's.
• zoom - zooms the current window